home *** CD-ROM | disk | FTP | other *** search
- *intro.txt* For Vim version 5.0. Last modification: 1998 Feb 16
-
-
- VIM REFERENCE MANUAL by Bram Moolenaar
-
-
- Introduction to Vim *ref* *reference*
-
- 1. Introduction |intro|
- 2. Vim on the internet |internet|
- 3. Credits |credits|
- 4. Notation |notation|
- 5. Modes, introduction |vim-modes-intro|
- 6. Switching from mode to mode |mode-switching|
- 7. The window contents |window-contents|
-
- ==============================================================================
- 1. Introduction *intro*
-
- Vim stands for Vi IMproved. It used to be Vi IMitation, but there are so many
- improvements that a name change was appropriate. Vim is a text editor which
- includes almost all the commands from the Unix program "Vi" and a lot of new
- ones. It is very useful for editing programs and other 8-bit ASCII text. All
- commands are given with the keyboard. This has the advantage that you can
- keep your fingers on the keyboard and your eyes on the screen. For those who
- want it, there is mouse support and a GUI version with scrollbars and menus
- (see |gui.txt|).
-
- Throughout this manual the differences between Vi and Vim are mentioned in
- curly braces. See |vi_diff.txt| for a summary of the differences.
-
- This manual refers to Vim on various machines. There may be small differences
- between different computers and terminals. Besides the remarks given in this
- document, there is a separate document for each supported system, see
- |sys-file-list|.
-
- This manual is a reference for all the Vim commands and options. This is not
- an introduction to the use of Vim. There are many books on Vi that contain a
- section for beginners. I can recommend "Learning the Vi editor", by Linda
- Lamb, published by O'Reilly. But, that book is for Vi, not for Vim.
-
- A summary of this manual can be found in the file "help.txt",
- |help.txt|. It can be accessed from within Vim with the <Help> or <F1>
- key and with the command ":help", |:help|. The 'helpfile' option can be set
- to the name of the help file, so you can put it in any place you like.
-
- ==============================================================================
- 2. Vim on the internet *internet*
-
- *www* *faq* *FAQ* *ftp* *distribution* *download*
- The Vim pages contain the most recent information about Vim. They also
- contain links to the most recent version of Vim. The FAQ is a list of
- Frequently Asked Questions. Read this if you have problems.
-
- VIM home page: <URL:http://www.vim.org/>
- VIM FAQ: <URL:http://www.vim.org/faq/>
-
-
- Usenet News group where Vim is discussed: *news* *usenet*
- comp.editors
- See <URL:http://www.vim.org/news.html>.
-
- *vimdev* *mail-list*
- There are three mailing lists for Vim:
- <vim@vim.org>
- For discussions about using existing versions of Vim: Useful mappings,
- questions, answers, where to get a specific version, etc.
- <vim-dev@vim.org>
- For discussions about changing Vim: New features, porting, beta-test
- versions, etc.
- <vim-announce@vim.org>
- Announcements about new versions of Vim; also beta-test versions and
- ports to different systems.
-
- See <URL:http://www.vim.org/mail.html>.
-
- NOTE:
- - You can only send messages to these lists if you have subscribed!
- - You need to send the messages from the same location as where you subscribed
- from (to avoid spam mails).
- - Maximum message size is 40000 characters.
-
- If you want to join, send a message to
- <vim-help@vim.org>
- Make sure that your "From:" address is correct. Then the list server will
- give you help on how to subscribe.
-
- An archive is kept at:
- <URL:ftp://ftp.ii.uib.no/pub/vim/mail-archive/vim/maillist.html>
- <URL:ftp://ftp.ii.uib.no/pub/vim/mail-archive/vimdev/maillist.html>
- <URL:ftp://ftp.ii.uib.no/pub/vim/mail-archive/vimannounce/maillist.html>
- [Note: it doesn't work anymore]
-
- This was announced, but I don't think it works:
- <URL:http://www.findmail.com/listsaver/vimannounce.html>
-
-
- Bug reports: *bugs* *bug-reports* *bugreport.vim*
- Bram Moolenaar <Bram@vim.org>
- Please be brief; all the time that is spend on answering mail is subtracted
- from the time that is spent on improving Vim! Always give a reproduceable
- example and try to find out which settings or other things influence the
- appearance of the bug. Try different machines, if possible. Send me patches
- if you can!
-
- In case of doubt, use:
- > :so $VIM/bugreport.vim
- This will create a file "bugreport.txt" in the current directory, with a lot
- of information of your environment. Before sending this out, check if it
- doesn't contain any confidential information!
-
- When Vim crashes in one of the test files, and you are using gcc for
- compilation, here is what you can do to find out exactly where Vim crashes:
-
- 1. Compile Vim with the "-g" option (there is a line in the Makefile for this,
- which you can uncomment).
-
- 2. Execute these commands (replace "11" with the test that fails):
- > cd testdir
- > gdb ../vim
- > run -u NONE -s dotest.in test11.in
-
- 3. Check where Vim crashes, gdb should give a message for this.
-
- 4. Get a stack trace from gdb with this command:
- > where
-
- *year-2000*
- Since Vim internally doesn't use dates, there is no year 2000 problem.
- There might be a year 2038 problem, when the seconds since January 1st 1970
- don't fit in a 32 bit int anymore. This depends on the compiler, libraries
- and operating system. Specifically, time_t and the ctime() function are used.
- And the time_t is stored in four bytes in the swap file. But that's only used
- for printing a file date/time for recovery.
-
- ==============================================================================
- 3. Credits *credits* *author*
-
- Most of Vim was written by Bram Moolenaar <Bram@vim.org>.
-
- Parts of the documentation come from several Vi manuals, written by:
- W.N. Joy
- Alan P.W. Hewett
- Mark Horton
-
- The Vim editor is based on Stevie and includes (ideas from) other software,
- worked on by the people mentioned here. Other people helped by sending me
- patches, suggestions and giving feedback about what is good and bad in Vim.
-
- Vim would never have become what it is now, without the help of these people!
-
- Ron Aaron Win32 GUI changes
- Dany St-Amant Macintosh port
- Tony Andrews Stevie
- Gert van Antwerpen changes for DJGPP on MS-DOS
- Berkeley DB(3) ideas for swap file implementation
- Keith Bostic Nvi
- Ralf Brown SPAWNO library for MS-DOS
- Robert Colon many useful remarks
- Kayhan Demirel sent me news in Uganda
- Chris & John Downey xvi (ideas for multi-windows version)
- Eric Fischer Mac port, 'cindent', and other improvements
- Bill Foster Athena GUI port
- Loic Grenie xvim (ideas for multi windows version)
- Sven Guckes Vim WWW page maintainer
- Darren Hiebert Exhuberant ctags
- Steve Kirkendall Elvis
- Sergey Laskavy Vim's help from Moscow
- Felix von Leitner Maintainer of Vim Mailing Lists
- David Leonard Port of Python extensions to Unix
- Avner Lottem Edit in right-to-left windows
- Paul Moore Python interface extensions
- George V. Reilly Win32 port, Win32 GUI start-off
- Stephen Riehm bug collector
- Olaf Seibert DICE and BeBox version, regexp improvements
- Mortaza Shiran Farsi patches
- Peter da Silva termlib
- Paul Slootman OS/2 port
- Henry Spencer regular expressions
- Tim Thompson Stevie
- G. R. (Fred) Walter Stevie
- Sven Verdoolaege Perl interface
- Robert Webb Command-line completion, GUI versions, and
- lots of patches
- Juergen Weigert Lattice version, AUX improvements, UNIX and
- MS-DOS ports, autoconf
- Stefan 'Sec' Zehl Maintainer of vim.org
-
- I wish to thank all the people that sent me bug reports and suggestions. The
- list is too long to mention them all here. Vim would not be the same without
- the ideas from all these people: They keep Vim alive!
-
- ==============================================================================
- 4. Notation *notation*
-
- [] Characters in square brackets are optional.
-
- *count* *[count]*
- [count] An optional number that may precede the command to multiply
- or iterate the command. If no number is given, a count of one
- is used, unless otherwise noted. Note that in this manual the
- [count] is not mentioned in the description of the command,
- but only in the explanation. This was done to make the
- commands easier to look up. If the 'showcmd' option is on,
- the (partially) entered count is shown at the bottom of the
- window. You can use <Del> to erase the last digit (|N<Del>|).
-
- *[quotex]*
- ["x] An optional register designation where text can be stored.
- See |registers|. The x is a single character between 'a' and
- 'z' or 'A' and 'Z' or '"', and in some cases (with the put
- command) between '0' and '9', '%', '#', ':' or '.'. The
- uppercase and lower case letter designate the same register,
- but the lower case letter is used to overwrite the previous
- register contents, while the uppercase letter is used to
- append to the previous register contents. Without the ""x" or
- with """" the stored text is put into the unnamed register.
-
- *{}*
- {} Curly braces denote parts of the command which must appear,
- but which can take a number of different values. The
- differences between Vim and Vi are also given in curly braces
- (this will be clear from the context).
-
- *{motion}*
- {motion} A command that moves the cursor. See the list at
- |motion.txt|. This is used after an operator command
- |operator| to move over the text that is to be operated upon.
- If the motion includes a count and the operator also had a
- count, the two counts are multiplied. For example: "2d3w"
- deletes six words. The motion can also be a mouse click. The
- mouse is currently only supported for MS-DOS, Win32 and xterm
- under Unix. The ":omap" command can be used to map characters
- while an operator is pending.
-
- *{Visual}*
- {Visual} A piece of text that is started with the "v", "V", or CTRL-V
- command and ended by the cursor position. This is used
- before an operator command |operator| to highlight the text
- that is to be operated upon. See |Visual-mode|.
-
- *<character>*
- <character> A special character from the table below or a single ASCII
- character.
-
- *'character'*
- 'character' A single ASCII character.
-
- *<char1-char2>*
- <char1-char2> A single character from the range <char1> to <char2>. For
- example: <a-z> is a lowercase letter. Multiple ranges may be
- concatenated. For example, <a-zA-Z0-9> is any alphanumeric
- character.
-
- *CTRL-{char}*
- CTRL-{char} {char} typed as a control character; that is, typing {char}
- while holding the CTRL key down. The case of {char} does not
- matter; thus CTRL-A and CTRL-a are equivalent. But on some
- terminals, using the SHIFT key will produce another code,
- don't use it then.
-
- *'option'*
- 'option' An option, or parameter, that can be set to a value, is
- enclosed in single quotes. See |options|.
-
- *quotecommandquote*
- "command" In examples, the commands you can type are enclosed in double
- quotes.
-
- *key-notation* *key-codes*
- These names for keys are used in the documentation. They can also be used
- with the ":map" command.
-
- notation meaning equivalent decimal value(s) ~
- -----------------------------------------------------------------------
- <Nul> zero CTRL-@ 0 (stored as 10) *<Nul>*
- <BS> backspace CTRL-H 8 *backspace*
- <Tab> tab CTRL-I 9 *tab*
- *linefeed*
- <NL> linefeed CTRL-J 10 (used for <Nul>)
- <FF> formfeed CTRL-L 12 *formfeed*
- <CR> carriage return CTRL-M 13 *carriage-return*
- <Enter> same as <CR> *<Enter>*
- <Esc> escape CTRL-[ 27 *escape* *<Esc>*
- <Space> space 32 *space*
- <Del> delete 127
- <Bar> vertical bar | 124 *<Bar>*
- <Bslash> backslash \ 92 *backslash* *<Bslash>*
-
- <EOL> end-of-line (can be <CR>, <LF> or <CR><LF>,
- depends on system and 'fileformat') *<EOL>*
-
- <Up> cursor-up *cursor-up* *cursor_up*
- <Down> cursor-down *cursor-down* *cursor_down*
- <Left> cursor-left *cursor-left* *cursor_left*
- <Right> cursor-right *cursor-right* *cursor_right*
- <S-Up> shift-cursor-up
- <S-Down> shift-cursor-down
- <S-Left> shift-cursor-left
- <S-Right> shift-cursor-right
- <C-Left> control-cursor-left
- <C-Right> control-cursor-right
- <F1> - <F12> function keys 1 to 12 *function_key* *function-key*
- <S-F1> - <S-F12> shift-function keys 1 to 12 *<S-F1>*
- <Help> help key
- <Undo> undo key
- <Insert> insert key
- <Home> home *home*
- <End> end *end*
- <PageUp> page-up *page_up* *page-up*
- <PageDown> page-down *page_down* *page-down*
- <kHome> keypad home (upper left) *keypad-home*
- <kEnd> keypad end (lower left) *keypad-end*
- <kPageUp> keypad page-up (upper right) *keypad-page-up*
- <kPageDown> keypad page-down (lower right) *keypad-page-down*
- <S-...> shift-key *shift*
- <C-...> control-key *control* *ctrl*
- <M-...> alt-key or meta-key *meta* *alt*
- <t_xx> key with "xx" entry in termcap
- -----------------------------------------------------------------------
-
- Note: The shifted cursor keys, the help key, and the undo key are only
- available on a few terminals. On the Amiga, shifted function key 10 produces
- a code (CSI) that is also used by key sequences. It will be recognized only
- after typing another key.
-
- Note: There are two codes for the delete key. 127 is the decimal ASCII value
- for the delete key, which is always recognized. Some delete keys send another
- value, in which case this value is obtained from the termcap entry "kD". Both
- values have the same effect. Also see |:fixdel|.
-
- Note: The keypad keys are used in the same way as the corresponding "normal"
- keys. For example, <kHome> has the same effect as <Home>. If a keypad key
- sends the same raw key code as it non-keypad equivalent, it will be recognized
- as the non-keypad code. For example, when <kHome> sends the same code as
- <Home>, when pressing <kHome> Vim will think <Home> was pressed. Mapping
- <kHome> will not work then.
-
- *<>*
- Examples are often given in the <> notation. Sometimes this is just to make
- clear what you need to type, but often it can be typed literally, e.g., with
- the ":map" command. The rules are:
- 1. Any printable characters are typed directly, except backslash and '<'
- 2. A backslash is represented with "\\", double backslash.
- 3. A real '<' is represented with "\<".
- 4. "<key>" means the special key typed. This is the notation explained in
- the table above. A few examples:
- <Esc> Escape key
- <C-G> CTRL-G
- <Up> cursor up key
- <C-LeftMouse> Control- left mouse click
- <S-F11> Shifted function key 11
- <M-a> Meta- a ('a' with bit 8 set)
- <M-A> Meta- A ('A' with bit 8 set)
- <t_kd> "kd" termcap entry (cursor down key)
-
- If you want to use the full <> notation in Vim, you have to remove the 'B'
- flag from 'cpoptions' and make sure the '<' flag is excluded (it already is by
- default).
- :set cpo=ceFs
- If you have the 'B' flag in 'cpoptions', then <> notation mostly still works,
- but you can't escape the special meaning of key names in <> with a backslash.
- To distinguish using <> with and without the 'B' flag, it's called full <>
- notation if the 'B' flag is excluded.
- For mapping, abbreviation and menu commands you can then copy-paste the
- examples and use them directly. Or type them literally, including the '<' and
- '>' characters. This does NOT work for other commands, like ":set" and
- ":autocmd"!
-
-
- There are several references to other versions of Vi:
- *Vi*
- Vi "the original". Without further remarks this is the version
- of Vi that appeared in Sun OS 4.x. ":version" returns
- "Version 3.7, 6/7/85". Sometimes other versions are referred
- to. Only runs under Unix. Source code only available with a
- license. More information on Vi can be found through:
- <URL:http://www.vim.org>
-
- *Posix*
- Posix From the IEEE standard 1003.2, Part 2: Shell and utilities.
- Generally known as "Posix". This is a textual description of
- how Vi is supposed to work. The version used is a draft from
- beginning 1996, so all remarks are "expected to comply to"
- this. Anything can change though...
- *Nvi*
- Nvi The "New" Vi. The version of Vi that comes with BSD 4.4 and
- many free Unix versions. The version used is 1.79.
- ":version" returns "Version 1.79 (10/23/96)". Source code is
- freely available.
- *Elvis*
- Elvis Another Vi clone, made by Steve Kirkendall. The version used
- is 2.1b, which is a beta-test version. Version 2.0 is the
- last official release. Source code is freely available.
-
- ==============================================================================
- 5. Modes, introduction *vim-modes-intro* *vim-modes*
-
- Vim has five BASIC modes:
-
- Normal mode In Normal mode you can enter all the editor
- commands. If you start the editor you are in this
- mode (unless you have set the 'insertmode' option,
- see below). This is also known as command mode.
-
- Visual mode This is like Normal mode, but the movement commands
- extend a highlighted area. When a non-movement
- command is used, it is executed for the highlighted
- area. See |Visual-mode|.
-
- Insert mode In Insert mode the text you type is inserted into the
- buffer. If the 'showmode' option is on (which is
- default), the string "-- INSERT --" is shown at the
- bottom of the window. |mode-ins-repl|
-
- Command-line mode In Command-line mode you can enter one line of text
- at the bottom of the window. This is for the Ex
- commands, ":", the pattern search commands, "?" and
- "/", and the filter command, "!". |mode-cmdline|
-
- Ex mode Like Command-line mode, but after entering a command
- you remain in Ex mode. Very limited editing of the
- command. |mode-Ex|
-
- There are two ADDITIONAL modes:
-
- Replace mode Replace mode is a special case of Insert mode. You
- can do the same things as in Insert mode, but for
- each character you enter, one character of the existing
- text is deleted. If the 'showmode' option is on,
- (which is the default), the string "-- REPLACE --" is
- shown at the bottom of the window. |replace-mode|
-
- Insert command mode Entered when CTRL-O given in Insert mode. This is
- like Normal mode, but after executing one command Vim
- returns to Insert mode. The string "-- (insert) --"
- is shown at the bottom of the window.
-
-
- ==============================================================================
- 6. Switching from mode to mode *mode-switching*
-
- If for any reason you do not know which mode you are in, you can always get
- back to Normal mode by typing <Esc> twice. You will know you are back in
- Normal mode when you see the screen flash or hear the bell after you type
- <Esc>. This doesn't work for Ex mode, use ":visual".
-
- *i_esc*
- TO mode ~
- Normal Visual Insert Replace Cmd-line Ex ~
- FROM mode ~
- Normal - v V ^V *1 R : / ? ! Q
- Visual *2 - c C -- : --
- Insert <Esc> -- - <Insert> -- --
- Replace <Esc> -- <Insert> - -- --
- Command-line *3 -- -- -- - --
- Ex :vi -- -- -- -- -
-
- - NA
- -- not possible
-
- *1 Go from Normal mode to Insert mode by giving the command "i", "I", "a",
- "A", "o", "O", "c", "C", "s" or S".
- *2 Go from Visual mode to Normal mode by giving a non-movement command, which
- causes the command to be executed, or by hitting <Esc> "v", "V" or "CTRL-V"
- (see |v_v|), which just stops Visual mode without side effets.
- *3 Go from Command-line mode to Normal mode by:
- - Hitting <CR> or <NL>, which causes the entered command to be executed.
- - Deleting the complete line (e.g., with CTRL-U) and giving a final <BS>.
- - Hitting CTRL-C or <Esc>, which quits the command line without executing
- the command.
- In the last case <Esc> may be the character defined with the 'wildchar'
- option, in which case it will start command line completion. You can
- ignore that and type <Esc> again. {Vi: when hitting <Esc> the command line
- is executed. This is unexpected for most people; therefore it was changed
- in Vim. But when the <Esc> is part of a mapping, the command line is
- executed. If you want the Vi behaviour also when typing <Esc>, use ":cmap
- ^V<Esc> ^V^M"}
-
- If the 'insertmode' option is on, editing a file will start in Insert mode.
-
- *Q* *mode-Ex* *ex-mode*
- Q Switch to "Ex" mode. This is a bit like typing ":"
- commands one after another, except:
- - You don't have to keep pressing ":".
- - The screen doesn't get updated after each command.
- - There is no normal command-line editing.
- - Mappings and abbreviations are not used.
- In fact, you are editing the lines with the "standard"
- line-input editing commands (<Del> or <BS> to erease,
- CTRL-U to kill the whole line).
- Vim will enter this mode by default if it's invoked as
- "ex" on the command line.
- Use the ":vi" command |:visual| to exit "Ex" mode.
-
- ==============================================================================
- 7. The window contents *window-contents*
-
- In command and Insert/Replace mode the screen window will show the current
- contents of the buffer: What You See Is What You Get. There are two
- exceptions:
- - When the 'cpoptions' option contains '$', and the change is within one line,
- the text is not directly deleted, but a '$' is put at the last deleted
- character.
- - When inserting text in one window, other windows on the same text are not
- updated until the insert is finished.
- {Vi: The screen is not always updated on slow terminals}
-
- Lines longer than the window width will wrap, unless the 'wrap' option is off
- (see below). The 'linebreak' option can be set to wrap at a blank character.
-
- The bottom lines in the window may start with one of these two characters:
-
- '@' The next line is too long to fit in the window.
- '~' Below the last line in the buffer.
-
- If the bottom line is completely filled with '@', the line that is at the
- top of the window is too long to fit in the window. If the cursor is on this
- line you can't see what you are doing, because this part of the line is not
- shown. However, the part of the line before the '@'s can be edited normally.
- {Vi: gives an "internal error" on lines that do not fit in the window}
-
- The '@' occasion in the 'highlight' option can be used to set special
- highlighting for the '@' and '~' characters.
-
- The 'showbreak' option contains the string to put in front of wrapped lines.
-
- *wrap-off*
- If the 'wrap' option is off, long lines will not wrap. Only the part that
- fits on the screen is shown. If the cursor is moved to a part of the line
- that is not shown, the screen is scrolled horizontally. The advantage of
- this method is that columns are shown as they are and lines that cannot fit
- on the screen can be edited. The disadvantage is that you cannot see all the
- characters of a line at once. The 'sidescroll' option can be set to the
- minimal number of columns to scroll. {Vi: has no 'wrap' option}
-
- All normal ASCII characters are displayed directly on the screen. The <Tab>
- is replaced with the number of spaces that it represents. Other non-printing
- characters are replaced with "^{char}", where {char} is the non-printing
- character with 64 added. Thus character 7 (bell) will be shown as "^G".
- Characters between 127 and 160 are replaced with "~{char}", where {char} is
- the character with 64 subtracted. These characters occupy more than one
- position on the screen. The cursor can only be positioned on the first one.
-
- If you set the 'number' option, all lines will be preceded with their
- number. Tip: If you don't like wrapping lines to mix with the line numbers,
- set the 'showbreak' option to eight spaces:
- ":set showbreak=\ \ \ \ \ \ \ \ "
-
- If you set the 'list' option, <Tab> characters will not be shown as several
- spaces, but as "^I". A '$' will be placed at the end of the line, so you can
- find trailing blanks.
-
- In Command-line mode only the command line itself is shown correctly. The
- display of the buffer contents is updated as soon as you go back to Command
- mode.
-
- The last line of the window is used for status and other messages. The
- status messages will only be used if an option is on:
-
- status message option default Unix default ~
- current mode 'showmode' on on
- command characters 'showcmd' on off
- cursor position 'ruler' off off
-
- The current mode is "-- INSERT --" or "-- REPLACE --", see |'showmode'|. The
- command characters are those that you typed but were not used yet. {Vi: does
- not show the characters you typed or the cursor position}
-
- If you have a slow terminal you can switch off the status messages to speed
- up editing:
- :set nosc noru nosm
-
- If there is an error, an error message will be shown for at least one second
- (in reverse video). {Vi: error messages may be overwritten with other
- messages before you have a chance to read them}
-
- Some commands show how many lines were affected. Above which threshold this
- happens can be controlled with the 'report' option (default 2).
-
- On the Amiga Vim will run in a CLI window. The name Vim and the full name of
- the current file name will be shown in the title bar. When the window is
- resized, Vim will automatically redraw the window. You may make the window as
- small as you like, but if it gets too small not a single line will fit in it.
- Make it at least 40 characters wide to be able to read most messages on the
- last line.
-
- On most Unix systems window resize works ok. {Vi: not ok}
-
- vim:ts=8:sw=8:tw=78:
-